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TABLE FORMATTING PROGRAM 
1. Introduction 


The tbl program is a document formatting preprocessor for the formatter which makes fairly complex ta- 
bles easy to specify and enter. Tables consist of columns which may be independently centered, right-adjusted, 
left-adjusted, or aligned by decimal points. Headings may be placed over single columns or groups of columns. 
A table entry may contain equations or consist of several rows of text. Horizontal or vertical lines may be drawn 
as desired in the table, and any table or element may be enclosed in a box. 


A description of a table is put by the tbl program into a troff formatter (the nroff and/or troff processor 
will be referred to synonymously as “formatter”) list of requests that prints the table. The tbl program isolates 
a portion of a job that can be successfully handled and leaves the remainder for other programs. Thus, tbl may 
be used with the equation formatting program (eqn) and/or various formatter layout macro packages without 
function duplication. 


2. Usage 


On the UNIX operating system, the tbl program can be run on a simple table with the command 


thl filename}! troff 


For more complicated use, where there are several input files containi ng equations and ms or mm macro re- 
quests as well as tables, the normal command is 


tbl filel file2 . . teqnitroff —ms 


The usual options may be used on the troff formatter and eqn commands. Usage of the nroff formatter is simi- 
lar to that of troff, but only TELETYPE® Model 37 and Diablo-mechanism (DASI or GST) terminals can print 
boxed tables. If a file name is “—”, the standard input is read at that point. 


For the convenience of users employing line printers without adequate driving tables or post-filters, there 
is a special — 7X command-line option to tbl which produces output that does not have fractional line motions. 
The only other command-line options recognized by tbl are —ms and —mm. They are turned into commands 
to fetch the corresponding macro files. It is usually more convenient to place these arguments on the troff 
formatter part of the command line, but they are accepted by tbl as well. 


When egn and tbl programs are used together on the same file, thl should be used first. If there are no 
equations within tables, either sequence works. It is usually faster to execute tbl first since eqn normally pro- 
duces a larger expansion of the input. However, if there are equations within tables (using the delim option in 
eqn), tbl must be executed first or the output will be scrambled. Use of equations in n-style columns should 
be avoided since tbl attempts to split numerical format items into two parts. The delim(xx) table option pre- 
vents splitting numerical columns within delimiters. For example, if the eqn delimiters are $$, giving delim($ 
$) causes a numerical column such as 1245 $1 16$ to be divided after 1245, not after 16. 


The tbl program accepts up to 35 columns; the actual number that can be processed may be smaller depend- 
ing on availability of troff formatter number registers. Number register names used by tbl must be avoided 
within tables. These include 2-digit numbers from 31 to 99 and strings of the form 4x, 5x, #x, xt, xl, *x, and 
x—, where xis any lowercase letter. The names ##, #—, and #* are also used in certain circumstances. To con- 
serve register names, the n and a key letters (key letters are introduced in the “Format Section” part that fol- 
lows) share a register; hence, the restriction that they may not be used in the same column. 


As an aid in writing layout macros, tbl defines a number register TW which is the table width. The TW 
number register is defined by the time the .TE macro is invoked and may be used in the expansion of that macro. 
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More importantly, to assist in laying out multipage boxed tables, the macro T# is defined to produce the bottom 
lines and side lines of a boxed table and then be invoked at its end. By use of this macro in the page footer, a 
multipage table can be boxed. In particular, the msand mm macros can be used to print a multipage boxed table 
with a repeated heading by giving the argument H to the .TS macro. If the table start macro is written 


TS H 
a line of the form 

mii a 
must be given in the table after any table heading (or at the start if none). Material up to the .TH is placed 
at the top of each page of the table. The remaining lines in the table are placed on several pages as required. 
This is not a feature of tbl but of the ms and mm macros. 
3. Input Commands 

Input to tbl is text for a document with tables preceded by a .TS (table start) command and followed by 

a .TE (table end) command. The tbl program processes the tables, generates formatting requests, and leaves 
the text unchanged. The .TS and .TE lines are copied so that troff formatter layout macros (such as memoran- 
dum formatting macros) can use these lines as delimiters. Arguments on the .TS or .TE lines are copied, but 


otherwise ignored, and may be used by document layout macro requests. 


The format of the input is 


The format of each table is 
TS 
options ; 
format. 
data 
TE 
Each table is independent and contains: 
e Global options 
e A format section describing individual columns and rows of the table 


e Data to be printed. 


The format section and data are always required but not the options. 
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3.1 Global Options 


There may be a single line of options affecting the whole table. If present, this line must immediately follow 
the .TS line and must contain a list of option names separated by spaces, tabs, or commas and must be termi- 
nated by a semicolon. Allowable options are: 

e center—center table (default is left-adjust) 

e expand—make table as wide as current line length 

e box—enclose table in a box 

e allbox—enclose each item of table in a box 

e doublebox—enclose table in two boxes 

e tab (x)—separate data items by using x instead of tab 

e linesize (n)~set lines or rules (e.g., from box) in n-point type 

e delim (xy)—recognize x and yas egn delimiters. 
The tbl program tries to keep boxed tables on one page by issuing appropriate .ne (need) requests. These re- 
quests are calculated from the number of lines in the tables. If there are spacing requests embedded in the input, 
the .ne requests may be inaccurate. Normal troff formatter procedures, such as keep-release macros, are used 
in that case. If a multipage boxed table is required, macros designed for this purpose (.TS H and .TH) should 
be used. 
3.2 Format Section 

The format section of the table specifies the layout of the columns. Each line in the format section corre- 
sponds to one line of table data (except that the last format line corresponds to all following data lines up to 


any additional .T& command line). Each line contains a key letter for each column of the table. Key letters 
for each column may be separated by spaces or tabs for readibility purposes. Key letters are: 


Lorl Indicates a left-adjusted column entry. 

Rorr Indicates a right-adjusted column entry. 

Core Indicates a centered column entry. 

Norn Indicates a numerical column entry. Numcrical entries are aligned so that the units digits 


of numbers line up. 


Aora_ Indicates an alphabetic subcolumn. All corresponding entries are aligned on the left and 
positioned so that the widest entry is centered within the column. 


Sors Indicates a spanned heading. The entry from the previous column continues across this col- 
umn (not allowed for the first column of the table), 


Indicates a vertically spanned heading. The entry from the previous row continues down 
through this row (not allowed for the first row of the table). 


When numerical column alignment (n) is specified, a location for the decimal point is sought. The rightmost 
dot (.) adjacent to a digit is used as a decimal point. If there is no dot adjoining a digit, the rightmost digit is 
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used as a units digit. If no alignment is indicated, the item is centered in the column. However, the special non- 
printing character string \& may be used to override dots and digits or to align alphabetic data. This string 
lines up where a dot normally would and then disappears from the final output. In the following example, items 
shown in the left column will be aligned (in a numerical column) as shown in the right column: 


13 13 

4,2 4.2 
26.4.12 26.4.12 
abedefg abcdefg 
abedefg\ & abedefg 

43 \ &3.22 433.22 
749.12 749.12 


If numerical data are used in the san.e column with wider L (the capital L key letter is used instead of lower- 
case for readability) or r-type table entries, the widest number is centered relative to the wider L or r items. 
Alignment within the numerical items is preserved. This is similar to the behavior of a-type data. Alphabetic 
subcolumns (requested by the a key letter) are always slightly indented relative to L items. If necessary, the 
column width is increased to force this. This is not true for n-type entries. 


Note: Then and a items should not be used in the same column. 


The end of the format section is indicated by a period. The layout of key letters in the format section resem- 
bles the layout of the actual data in the table. Thus, a simple 3-column format might appear as 


css 
Inn. 


The first line of the table contains a heading centered across all three columns. Each remaining line contains 
a left-adjusted item in the first column followed by two columns of numerical data. A sample table in this for- 
mat is: 


OVERALL TITLE 


Item-a 34.22 9.1 
Item-b 12.65 02 
Items: e,dje 28 5.8 
Total 69.87 14.92 


Instead of listing the format of successive lines of a table on consecutive lines of the format section, succes- 
sive line formats may be given on the same line, separated by commas. The format for the above example could 
be written: 

ess1 nn. 


Additional features of the key letter system are: 


e Horizontal lines—A key letter may be replaced by underscore (_) to indicate a horizontal line in place 
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of the column entry or equal (=) to indicate a double horizontal line. If an adjacent column contains 
a horizontal line or if there are vertical lines adjoining this column, the horizontal line is extended to 
meet nearby lines. If any data entry is provided for this column, it is ignored and a warning message 
is printed. 


Vertical lines—A vertical bar (|) placed between column key letters will cause a vertical line between 
the corresponding columns of the table. A vertical bar to the left of the first key letter or to the right 
of the last one produces a line at the edge of the table. If two vertical bars appear between key letters, 
a double vertical line is drawn. 


Space between columns—A number may follow the key letter indicating the amount of separation be- 
tween this column and the next column. The number specifies the separation in ens. One en is about 
the width of the letter “n”. More precisely, an en is the number of points (1 point = 1/72 inch) equal 
to half the current type size. If the expand option is used, these numbers are multiplied by a constant 
such that the table is as wide as the current line length. The default column separation number is 3. 
If the separation is changed, the worst case (largest space requested) governs. 


Vertical spanning— Vertically spanned items extending over several rows of the table are centered in 
their vertical range. If a key letter is followed by t or T, any corresponding vertically spanned item will 
begin at the top line of its range. 


Font changes—A key letter followed by a string containing a font name or number preceded by the letter 
f or F indicates that the corresponding column should be in a different font from the default font (usu- 
ally Roman). All font names are one or two letters. A 1-letter font name should be separated from what- 
ever follows by a space or tab. The single letters B, b, I, and i are shorter synonyms for fB and fI. Font- 
change requests given with the table entries override these specifications. 


Point size changes—A key letter followed by p or P and a number indicates the point size of the corre- 
sponding table entries. If the number is a signed digit, it is taken as an increment or decrement from 
the current point size. If both a point size and a column separation value are given, one or more blanks 
must separate them. 


Vertical spacing changes—A key letter followed by v or V and a number indicates the vertical line spac- 
ing used within a multiline table entry. The number may be a signed digit, in which ease it is taken as 
an increment or decrement from the current vertical spacing. A column separation value must be sepa- 
rated by blanks or some other specification from a vertical spacing request. This request has no effect 
unless the corresponding table entry is a text block. 


Column width indication—A key letter followed by w or W and a width value in parentheses indicates 
minimum column width. If the largest element in the column is not as wide as the width value given 
after the w, the largest element is assumed to he that wide. If the largest element in the column is wider 
than the specified value, its width is used. The width is also used as a default: line length for included 
text blocks. Normal troff formatter units can be used to scale the width value. The default value is ens 
if none are used. If the width specification is a unitless integer, the parentheses may be omitted. If an- 
other width value is given in a column, the last one controls the width. 


Equal-width columns—A key letter followed by e or E indicates equal-width columns. All columns 


whose key letters are followed by e or E are made the same width. This permits a group of regularly 
spaced columns. 


Staggered columns—A key letter followed by u or U indicates that the corresponding entry is to be 
moved up one-half line. This makes it easy to have a column of differences between numbers in an ad- 
joining column. The allbox option does not work with staggered columns. 


Zero-width item—A key letter followed by z or Z indicates that the corresponding data item is to be 
ignored in calculating column widths. This may be useful in allowing headings to run across adjacent 
columns where spanned headings would be inappropriate. 
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e Default—Column descriptors missing from the end of a format line are assumed to be L. The longest 
line in the format section, however, defines the number of columns in the table. Extra columns in the 
data are ignored. 


The order of the features is immaterial. They need not be separated by spaces except as indicated to avoid 
ambiguities involving point size and font changes. Thus, a numerical column entry in italic font and 12-point 
type with a minimum width of 2.5 inches and separated by 6 ens from the next column could be specified as 


npl2w(2.5i)f1 6 
3.3 Data To Be Printed 


Data for the table are input after the format section. Each table line is typed as one line of data. Very long 
. input lines can be broken. Any line whose last character is a backslash (\) is combined with the following line 
(i.e., the \ vanishes). Data for different columns (table entries) are separated by tabs or by whatever character 
has been specified in the tab global option. There are a few special cases of data entries: 


e troff commands within tables—An input line beginning with a dot and followed by anything but a num- 
ber (.xx) is assumed to be a request to the formatter and is passed through unchanged, retaining its posi- 
tion in the table. For example, a space within a table may be produced with the .sp request in the data. 


e Full width horizontal lines—An input line containing only the _ (underscore) character or = (equal 
sign) is taken to be a single or double line, respectively, extending the full width of the table. 


e Single column horizontal lines—An input table entry containing only the _ character or the = is taken 
to be a single or double line extending the full width of the column. Such lines are extended to meet hori- 
zontal or vertical lines adjoining this column. To obtain these characters explicitly in a column, they 
should be preceded by a \& or followed by a space before the usual tab or newline character. 


e Short horizontal lines—An input table entry containing only the string \_ is assumed to be a single 
line as wide as the contents of the column. It is not extended to meet adjoining lines. 


e Repeated characters—An input table entry containing only a string of the form \Rx, where x is any 
character, is replaced by repetitions of the character x as wide as data in the column. The sequence is 
not extended to meet adjoining columns. 


e Vertically spanned items—An input table entry containing only the \* character string indicates that 
the table entry immediately above spans downward over this row. It is equivalent to a table format key 
letter of *. 


e Text blocks—In order to include a block of text as a table entry, precede it by T{ and follow it by T}. 
Thus, the sequence 


eye aee 
is the way to enter as a single entry in the table something that cannot conveniently be typed as a simple 
string between tabs. The T} (end delimeter) must begin a line. Additional columns of data may follow 
after a tab on the same line. 


Various limits in the troff program are likely to be exceeded if 30 or more text blocks are used in a table. 
This produces diagnostic messages such as “too many string/macro names” or “too many number regis- 
ters”’. 


Page 102 


6/82 ISSUE 1 DOCUMENT PROCESSING GUIDE 


Text blocks are pulled out from the table, processed separately by the formatter, and replaced in the 
table as a solid block. 


If no line length is specified in the block of text or in the table format, the default is to use 
Ex C/ (N+ 1) 


where L is the current line length, Cis the number of table columns spanned by the text, and Nis the 
total number of columns in the table. 


Other parameters (point size, font, etc.) used in setting the block of text are: 
(a) Those in effect at the beginning of the table (including the effect of the .TS macro) 


(b) Any table format specifications of size, spacing, and font using the p, v, and f modifiers to the 
column key letters 


(c) troff requests within the text block itself (requests within the table data but not within the text 
block do not affect that block). 


Although any number of lines may be present in a table, only the first 200 lines are used in setting up the 
table. A multipage table may be arranged as several single-page tables if this proves to be a problem. 


When calculating column widths, all table entries are assumed to be in the font and size being used when 
the .TS command was encountered. This is true except for font and size changes indicated in the table format 
section or within the table data (as in the entry \s+3 data\fP\s0). Because arbitrary troff requests may be 
sprinkled in a table, care must be taken to avoid confusing width calculations. It is not possible to change the 
number of columns, the space between columns, the global options such as box, or the selection of columns to 
be made equal in width. 


4. Additional Command Lines 


To change the format of a table after many similar lines, as with subheadings or summarizations, the .T& 
(table continue) command is used to change column parameters. It is not recognized after the first 200 lines 
of a table. The outline of such a table input is 


TS 
options ; 
format. 
data 
TE& 
format. 
data 
.T& 
format. 
data 
TE 


Using this procedure, each table can be close to its corresponding format line. 
5. Examples 


Figures 3.3 through 3.8 are included to show input and output information that illustrates the basic concepts 
of the tbl program. The WU symbol in the input data represents a tab character. Although each figure has a title 
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that indicates an option or feature, other examples of use may be gleaned from them. For instance, Fig. 3.7 also 
indicates the requesting of bold type print in the format area. 
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